.\"	$Id: pforge.3,v 1.1.1.1 2005/05/31 18:19:16 jfb Exp $
.\"
.\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May, 9 2005
.Os
.Dt PFORGE 3
.Sh NAME
.Nm pforge
.Nd thread-safe packet and network information manipulation library
.Sh SYNOPSIS
.Fd #include <pforge/pforge.h>
.Ft int
.Fn pf_init "void"
.Ft int
.Fn pf_cleanup "void"
.Ft int
.Fn pf_geterr "void"
.Ft void
.Fn pf_seterr "int error"

.Ss Network Addresses
.Fd #include <pforge/addr.h>
.Ft PF_ADDR*
.Fn pf_addr_parse "int type" "const char *str"
.Ft void
.Fn pf_addr_free "PF_ADDR *addr"
.Ft int
.Fn pf_addr_cmp "const PF_ADDR *a1" "const PF_ADDR *a2"

.Ss Network Interfaces
.Fd #include <pforge/if.h>
.Ft int
.Fn pf_netif_create "int type" "const char *name" "int flags"
.Ft int
.Fn pf_netif_delete "int nid"
.Ft int
.Fn pf_netif_getindex "const char *name"
.Ft int
.Fn pf_netif_getinfo "int nid" "struct pf_netif_info *info"
.Ft int
.Fn pf_netif_open "int nid"
.Ft int
.Fn pf_netif_close "int nid"
.Ft int
.Fn pf_netif_sendpkt "int nid" "PF_PKT *pkt"
.Ft PF_PKT*
.Fn pf_netif_recvpkt "int nid"

.Ss Protocols
.Fd #include <pforge/proto.h>

.Ss Pseudo-Random Number Generation
.Ft int
.Fn pf_rand_get "uint8_t *dst" "size_t len"
.Ft uint16_t
.Fn pf_rand_get16 "void"
.Ft uint32_t
.Fn pf_rand_get32 "void"

.Sh DESCRIPTION
The
.Nm
provides several interfaces to ease the generation of network-oriented programs.
It abstracts the operating system's underlying interfaces to simplify
portability of programs as well.
The library was built from the ground up with thread-safety in mind, so it can
be used without problems with multithreaded applications.
.Pp
As opposed to most other network abstraction libraries, Packet Forge has no
knowledge of specific protocol internals.
It relies on a set of sub-libraries which must be loaded as necessary to
understand how to process and dispatch packets and how to parse network
addresses in various families.
.Pp
Before the library can be used, the
.Fn pf_init
function must be called to initialize the library's internals.


.Sh PACKET MANIPULATION
As opposed to most other network abstraction libraries, the packet manipulation
code has no knowledge of specific protocols.
A packet is merely treated as a sequential stream of bytes on which data can
be prepended, appended or removed.
The job of understanding the logical segments of the packet (headers,
checkums and such) is left to protocol-specific handlers.
This allows the library to be extremely flexible in the type of packets it
handles and the operations to perform on them.



.Sh PACKET INJECTION
Several routines are provided to access information about available network
interfaces on a host, as well as a limited set of manipulation routines,
depending on the system.


.Sh NETWORK INTERFACES


.Pp
.Sh NETWORK ADDRESSES


.Sh SEE ALSO
.Xr tcpdump 1 ,
.Xr pcap 3
.Sh HISTORY
Packet Forge originally started as a very simple program to perform quick
network tasks, but quickly transformed into a monster project that would take
on forever to finish.
.Sh AUTHORS
.An Jean-Francois Brousseau
.Sh BUGS
